Remove some alists from customize and update docs

The helper functions should be used now due to the nature of the lists.
Removing the variables from customize should encourage this.

Also add automatic conversion of old format of
`which-key-key-based-description-replacement-alist`.

diff --git a/README.org b/README.org
index ed9c48457fbc6a678e1c6c20cb0c90530eedcdb0..e83293471644090883d2c1bde91072f9dfcbb844 100644 (file)
--- a/README.org
+++ b/README.org
@@ -244,42 +244,34 @@ of behind each alist is that you specify a selection string in the =car= of each
 cons cell and the replacement string in the =cdr=.
 
 **** "Key-Based" replacement
-The relevant variable is the awkwardly named
-=which-key-key-based-description-replacement-alist= (Note on 3/9/2015 the
-internal format of this list changed). In this alist you can have cons cells of
-two types. An example of the first type is
+[Note on 2015-9-3 the format of
+=which-key-key-based-description-replacement-alist= changed. It will be easier
+to use the functions below in your configuration, instead of modifying this
+variable directly.]
+
+Using this method, the description of a key is replaced using a string that you
+provide. Here's an example 
 
 #+BEGIN_SRC Emacs-lisp
-((listify-key-sequence (kbd "C-x C-f")) . "find files")
+(which-key-add-key-based-replacements
+  "C-x C-f" "find files")
 #+END_SRC
 
-where the string on the left is the key combination whose description you want
-to replace, stored in a canonical form. For that key combination, which-key
+where the first string is the key combination whose description you want to
+replace, in a form suitable for =kbd=. For that key combination, which-key
 overwrites the description with the second string, "find files". In the second
 type of entry you can restrict the replacements to a major-mode. For example,
 
 #+BEGIN_SRC Emacs-lisp
-(org-mode . (((listify-key-sequence (kbd "C-c C-c")) . "Org C-c C-c") 
-             ((listify-key-sequence (kbd "C-c C-a")) . "Org Attach"))
-#+END_SRC
-
-Here the first entry is the major-mode and the second is a list of the first
-type of entries. In case the same key combination is listed under a major-mode
-and by itself, the major-mode version will take precedence.
-
-To simplify adding these entries, there are two helper functions to add entries
-to this list, =which-key-add-key-based-replacements= and
-=which-key-add-major-mode-key-based-replacements=. With these functions the
-above examples become
-
-#+BEGIN_SRC Emacs-lisp
-(which-key-add-key-based-replacements
-  "C-x C-f" "find files")
 (which-key-add-major-mode-key-based-replacements 'org-mode
   "C-c C-c" "Org C-c C-c"
   "C-c C-a" "Org Attach")
 #+END_SRC
 
+Here the first entry is the major-mode followed by a list of the first type of
+entries. In case the same key combination is listed under a major-mode and by
+itself, the major-mode version takes precedence.
+
 **** Key and Description replacement
 
 The second and third methods target the text used for the keys and the

diff --git a/which-key.el b/which-key.el
index 95bdca90666a5a2f4839ab19c5521f4dd2191368..028a99629aaa19b7b75ce13eb7a8f55273741e8e 100644 (file)
--- a/which-key.el
+++ b/which-key.el
@@ -104,21 +104,6 @@ This is a list of lists for replacing descriptions."
   :group 'which-key
   :type '(alist :key-type regexp :value-type string))
 
-(defcustom which-key-key-based-description-replacement-alist '()
-  "Each item in the list is a cons cell.
-The car of each cons cell is either a string like \"C-c\", in
-which case it's interpreted as a key sequence or a value of
-`major-mode'.  Here are two examples:
-
-(\"SPC f f\" . \"find files\")
-(emacs-lisp-mode . ((\"SPC m d\" . \"debug\")))
-
-In the first case the description of the key sequence \"SPC f f\"
-is overwritten with \"find files\". The second case works the
-same way using the alist matched when `major-mode' is
-emacs-lisp-mode."
-  :group 'which-key)
-
 (defcustom which-key-highlighted-command-list '()
   "A list of strings and/or cons cells used to highlight certain
 commands. If the element is a string, assume it is a regexp
@@ -126,25 +111,7 @@ pattern for matching command names and use
 `which-key-highlighted-command-face' for any matching names. If
 the element is a cons cell, it should take the form (regexp .
 face to apply)."
-  :group 'which-key-key-based-description-replacement-alist)
-
-(defcustom which-key-prefix-name-alist '()
-  "An alist with elements of the form (key-sequence . prefix-name).
-key-sequence is a sequence of the sort produced by applying `kbd'
-then `listify-key-sequence' to create a canonical version of the
-key sequence. prefix-name is a string."
-  :group 'which-key
-  :type '(alist :key-type string :value-type string))
-
-(defcustom which-key-prefix-title-alist '()
-  "An alist with elements of the form (key-sequence . prefix-title).
-key-sequence is a sequence of the sort produced by applying `kbd'
-then `listify-key-sequence' to create a canonical version of the
-key sequence. prefix-title is a string. The title is displayed
-alongside the actual current key sequence when
-`which-key-show-prefix' is set to either top or echo."
-  :group 'which-key
-  :type '(alist :key-type string :value-type string))
+  :group 'which-key)
 
 (defcustom which-key-special-keys '("SPC" "TAB" "RET" "ESC" "DEL")
   "These keys will automatically be truncated to one character
@@ -366,6 +333,28 @@ showing.")
   "Internal: Last location of side-window when two locations
 used.")
 
+(defvar which-key-key-based-description-replacement-alist '()
+  "New version of
+`which-key-key-based-description-replacement-alist'. Use
+`which-key-add-key-based-replacements' or
+`which-key-add-major-mode-key-based-replacements' to set this
+variable.")
+
+(defvar which-key-prefix-name-alist '()
+  "An alist with elements of the form (key-sequence . prefix-name).
+key-sequence is a sequence of the sort produced by applying `kbd'
+then `listify-key-sequence' to create a canonical version of the
+key sequence. prefix-name is a string.")
+
+(defvar which-key-prefix-title-alist '()
+  "An alist with elements of the form (key-sequence . prefix-title).
+key-sequence is a sequence of the sort produced by applying `kbd'
+then `listify-key-sequence' to create a canonical version of the
+key sequence. prefix-title is a string. The title is displayed
+alongside the actual current key sequence when
+`which-key-show-prefix' is set to either top or echo.")
+
+
 ;;;###autoload
 (define-minor-mode which-key-mode
   "Toggle which-key-mode."
@@ -408,6 +397,7 @@ set too high) and setup which-key buffer."
   (when (or (eq which-key-show-prefix 'echo)
             (eq which-key-popup-type 'minibuffer))
     (which-key--setup-echo-keystrokes))
+  (which-key--check-key-based-alist)
   (setq which-key--buffer (get-buffer-create which-key-buffer-name))
   (with-current-buffer which-key--buffer
     ;; suppress confusing minibuffer message
@@ -434,6 +424,36 @@ it's set too high)."
       ;;          previous echo-keystrokes)
       )))
 
+(defun which-key--check-key-based-alist ()
+  "Check (and fix if necessary) `which-key-key-based-description-replacement-alist'"
+  (let ((alist which-key-key-based-description-replacement-alist)
+        old-style res)
+    (dolist (cns alist)
+      (cond ((listp (car cns))
+             (push cns res))
+            ((stringp (car cns))
+             (setq old-style t)
+             (push (cons (listify-key-sequence (kbd (car cns))) (cdr cns)) res))
+            ((symbolp (car cns))
+             (let (new-mode-alist)
+               (dolist (cns2 (cdr cns))
+                 (cond ((listp (car cns2))
+                        (push cns2 new-mode-alist))
+                       ((stringp (car cns2))
+                        (setq old-style t)
+                        (push (cons (listify-key-sequence (kbd (car cns2))) (cdr cns2))
+                              new-mode-alist))))
+               (push (cons (car cns) new-mode-alist) res)))
+            (t (message "which-key: there's a problem with the \
+entry %s in which-key-key-based-replacement-alist" cns))))
+    (setq which-key-key-based-description-replacement-alist res)
+    (when old-style
+      (message "which-key: \
+ `which-key-key-based-description-replacement-alist' has changed format and you\
+ seem to be using the old format. Please use the functions \
+`which-key-add-key-based-replacements' and \
+`which-key-add-major-mode-key-based-replacements' instead."))))
+
 ;; Default configuration functions for use by users. Should be the "best"
 ;; configurations